/**
 * 支付回调控制器 - 处理ZPAY支付平台的回调通知接口
 *
 * 开发人员：徐少洋
 * 开发时间：2025-10-25 至 2025-10-28
 * 模块职责：处理ZPAY支付平台的异步通知和页面跳转回调，支持支付结果的接收和订单状态更新
 *
 * 技术要点：
 * - 异步通知接口（notify）处理支付结果
 * - 页面跳转接口（return）处理用户体验
 * - 签名验证和安全性处理机制
 * - 订单状态同步和业务逻辑处理
 * - 幂等性设计防止重复处理
 *
 * 开发故事：负责支付回调控制器的开发，与ZPAY支付平台和支付服务层深度配合，确保支付结果的准确接收和订单状态的正确更新。
 *
 * 注意事项：
 * - 本系统为PBL作业演示项目，采用"模拟支付"方式
 * - notify接口：异步回调（ZPAY服务器POST通知）- 本地开发环境无法接收
 * - return接口：同步跳转（用户支付完成后浏览器跳转）- 可在生产环境使用
 * - 演示流程：点击"模拟支付"→在新窗口打开ZPAY页面→手动点击"标记成功"完成订单
 * - 真实部署时需配置公网域名的notify_url，并实现签名验证和业务逻辑
 */
package com.pbl.controller;

import com.pbl.common.model.ApiResponse;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/payments")
public class PaymentCallbackController {

    /**
     * 异步通知接口（占位实现）
     * ZPAY文档：需返回纯字符串"success"，否则会重复通知
     * 本地开发时无法接收该回调，仅供部署后使用
     */
    @PostMapping("/notify")
    public String notifyCallback(@RequestParam Map<String, String> params) {
        // TODO: 生产环境需实现：
        // 1. 签名验证 ZpaySignUtil.buildSign()
        // 2. 订单金额校验
        // 3. 幂等性处理（防重复通知）
        // 4. 更新订单状态为SUCCESS
        System.out.println("收到ZPAY异步通知: " + params);
        return "success";
    }

    /**
     * 页面跳转通知接口（占位实现）
     * 用户支付完成后浏览器跳转到此接口
     */
    @GetMapping("/return")
    public ApiResponse<Map<String, String>> returnCallback(@RequestParam Map<String, String> params) {
        System.out.println("收到ZPAY页面跳转: " + params);
        // TODO: 生产环境需实现签名验证和页面展示
        return ApiResponse.success(params);
    }
}
